( ÷ BT E C H N O T E : *#QuickDraw GX OffscreenLibrary.c in *(Detail: Description, Uses & Limitations
*3
By Cary Clark ªª , Times * cary@artemis.com * Apple Emeritus *This Technote discusses , Geneva
)lOffscreenLibrary.c
)G" from the QuickDraw GX Libraries. (ˆ BJThis Note is intended for Macintosh QuickDraw GX developers who implement * .flickerless drawing or double buffering using
)ÉOffscreenLibrary.c
)G or who are (® BBconsidering using it for their QuickDraw GX graphics applications. 33ÿÿ
(î About the GX Libraries
+BKFor better or worse, the development of QuickDraw GX took seven years from * Nconception to initial release. During that time, there were many requests for * Lfeature enhancements and interface improvements that, if implemented, might * Hhave taken seven more years to complete. As it turns out, some of these * Senhancements could readily be built on existing services, but there was no time to * Stest or document these services with the rigor required to make them fully part of * the released system. ‡ª
å„î=÷ ÿÿ Apple Multiple Scan 17 - D50)Fî *#-pict Á Ú( E hB•$B≠B™(B• B∞ )Fî *Q @ @ -cnfoÿù-cnfo Ÿ¿C™? ÿ ÿÿÿÿ ( Ú ÿÄÿ◊
√° "ó•ó• √
√ ° # ‡x
U° #
ÿÜÿÜUÔ , Palatino
. +B TThe GX Libraries fill this gap by providing services built on top of the rest of GX * Kin source form. This Technote and others document these services. Since GX * Tlibraries are provided as source, it is reasonable for developers to modify them to * Qmeet their specific needs. Care was taken for the libraries not to depend on the * Gimplementation details of GX, so that future versions of GX should not * .invalidate them, in original or modified form. *MThe libraries are likely to evolve to take advantage of improved algorithms, * Pnew Macintosh or GX services; if you modify one for your applicationÕs specific * Mneeds, itÕs worth occasionally reviewing the GX library provided by Apple to * (stay synchronized with any improvements. ªª , Helvetica
*)What are Offscreens?
* Slick graphics )Dapplications attempt to )l# draw animations seamlessly to the ( Ï BJscreen, without flashing or flickering. QuickDraw GX provides a number of * Mstrategies that change these distractions into attractions. The most popular * method to eliminate flickering )‘1 is double buffering; the application draws into ( ó BMone bitmap while the computer displays a second bitmap. The bitmap receiving * Fthe drawing that will be displayed momentarily is called an offscreen. ªª
*) What is in OffscreenLibrary.c?
* The GX Library, , Geneva
)LOffscreenLibrary.c
)G1, provides utility functions to implement double (S BMbuffering; it creates bitmaps that in turn are imaged by GX Graphics. It was * Owritten primarily by Oliver Steele, with contributions from the rest of the GX * Graphics team.
*OffscreenLibrary.c
)GC has two distinct groups of functions. The simpler revolves around (≈ BQthe offscreen struct, and provides a single bitmap for back buffering. The other * Pset uses a viewPortBuffer to support multiple offscreens that correspond to the * Fportions of a window that spans multiple monitors of different depths. 33ÿÿ
(Ï Using OffscreenLibrary.c ªª
+B-'The One Shot Solution: Struct offscreen
* The meat of
)8Offscreenlibrary.c
)D is this struct:
(9 Cstruct offscreen { + >gxShape draw /* a bitmap which, when drawn, transfers ‡ª
. +Δ the offscreen to the display */ ( V=gxTransform xform; /* this causes shapes owning it to draw ( ! C* offscreen. */ + ?gxViewDevice device; /* the offscreen device whose colorSpace, ( 9 C3 etc. you may change */ + ?gxViewPort port; /* the offscreen port which may be put in ( Q C= any transform's viewPort list */ + ?gxViewGroup group; /* the global space in which the viewPort ( i C4 and viewDevice exist */ * }; , Palatino
( c BGNow, drawing the line bitmap will draw both the line and the rectangle:
+ GXDrawShape(lineBits);
( ˙ B Once youÕre done, you can use
)∞DisposeOffscreen
)E to get rid of it:
( · VDisposeOffscreen(&offLine);
( Ï B
The function
):
CopyToBitmaps
)=5 uses the offscreen structure internally to copy one ( Û BLbitmap onto another. The name is somewhat misleading, since the shape to be * Rcopied can be any shape type, not necessarily a bitmap. For instance, you can use * Cit to create a bitmap that has a specific bit depth from a picture:
+ 3static gxShape Create8BitPicture(gxShape myPicture) * { + gxRectangle bounds; (5 V&// get the bounding box of the picture + (GXGetShapeBounds(myPicture, 0, &bounds); (M V?// move the picture so that itÕs upper left corner is at (0, 0) + 2GXMoveShape(myPicture, -bounds.left, -bounds.top); (e V1// create a bitmap big enough to hold the picture + =gxShape bitmap = {nil, FixRound(bounds.right - bounds.left), + ;FixRound(bounds.bottom - bounds.top), 0, 8, nil, nil, nil}; (≈ V!// copy the picture to the bitmap + !CopyToBItmaps(bitmap, myPicture); (¡ V5// move the bitmap to the pictureÕs original position + 0GXMoveShape(myPicture, bounds.left, bounds.top); (’ V*// restore the pictureÕs original position + -GXMoveShape(bitmap, bounds.left, bounds.top); * return bitmap; († V} ªª , Helvetica
( B,The ViewPortBuffer Multiple Offscreen Scheme
* MThe Macintosh is relatively unique among computers in that it allows windows * Oto straddle two or more monitors at the same time. QuickDraw GX fully embraces * Sthis capability, and takes it to the logical extreme; not only can viewPorts cross * Mmultiple viewDevices, but the viewDevices themselves can overlap each other. ‡ª
å„î=÷ ÿÿ Apple Multiple Scan 17 - D50)Fî *#-pict Á Ú( ª E hB•$B≠B™(B• B∞ )Fî *Q @ @ -cnfoÿù-cnfo Ÿ¿C™? ÿ ÿÿÿÿ ( Ú ÿÄÿ◊
√° "ó•ó•
¨° # õà
U° #
ÿÜÿÜUÔ , Palatino
. +B MThis makes allocating an offscreen bitmap a challenge, since there may be no * Qsingle best depth that allows drawing to contain the correct amount of color and * 8draw as quickly as possible. The solution provided by a , Geneva
)ûviewPortBuffer
); creates a ( - BJpicture containing an array of offscreens that match the desired multiple * viewDevices. *HereÕs the interface to
)hviewPortBuffer
);.
( i V5typedef struct viewPortBufferRecord **viewPortBuffer;
( ™ BThe
)viewPortBuffer
);> is a blind handle that points to the internals kept by these ( Ÿ BQroutines. It is never necessary to directly access the fields pointed to by this * handle.
( Ï BKTo create an offscreen for a window that may cross multiple monitors, call * NNewViewPortBuffer. It takes the windowÕs viewPort, returns a reference to the * @internal structure. The windowÕs viewPort can be retrieved from
)[ to get deallocate the (5 B"internal objects allocated by the
)„viewPortBuffer
);.
(S V<gxViewPort GetViewPortBufferViewPort(viewPortBuffer source);
(k B.To draw shapes into the offscreen, first call
)ÆGetViewPortBufferViewPort
)n.
(w BGetViewPortBufferViewPort
)n1 returns a viewPort that references the multiple (∞ BRoffscreens. Drawing into this viewPort draws into as many offscreen bitmaps as is * Pappropriate. To attach this viewPort to a single shape, use the library routine
)b to get the shape to draw. (é BNDrawing the returned shape transfers the offscreen bitmaps to the viewDevices * Epointed to by the original viewPort, typically the windowÕs viewPort.
)X will put things right ( - B again. It returns true if the
)zviewPortBuffer
); was already valid. ( ? BIHereÕs a convoluted example that builds the offscreens and draws a shape.
+ 7static void BufferDraw(gxShape shape, WindowPtr window) * { * I// create the viewPortBuffer from the viewPort associated with the window + viewPortBuffer buffer = +` /NewViewPortBuffer(GXGetWindowViewPort(window)); ( ˙ CG// retrieve the viewPort created that allows drawing into the offscreen + ;viewPort offscreenPort = GetViewPortBufferViewPort(buffer); ( ± C$// point the shape to that offscreen + 'SetShapeViewPort(shape, offscreenPort); ( É C$// draw the shape into the offscreen + GXDrawShape(shape); ( á C%// draw the offscreen into the window + ,GXDrawShape(GetViewPortBufferShape(buffer)); ( ù C// throw the offscreen away + DisposeViewPortBuffer(buffer); ( C} ªª , Helvetica
(: B How the ViewPortBuffer Works
*
Since the
),viewPortBuffer
);4 is implemented as a library, you can read the code (e B3yourself; youÕll find it is pretty straightforward. *-The implementation is split into a few steps: +1. ) 5Figure out which devices the window/viewPort crosses. (§ E2. ) LFor each device, figure out the coordinates for the viewPort on that device. (¿ E3. ) LCreate a bitmap that has the same pixel depth, color set, color profile and * (color space as the corresponding device. (ã E4. ) OKeep track of the allocations and object references so that closing the window * L(or disposing the device) doesnÕt leave any dangling references or pointers. 33ÿÿ
( Summary
+BKGX Libraries contain a wealth of information and show how to use QuickDraw * GX to solve real problems.
)xOffscreenLibrary.c
)G" shows how to use GX to construct (9 BNflickerless drawing by implementing double buffering on a single device or on * multiple devices. ‡ª
) 8Inside Macintosh: QuickDraw GX Environment and Utilities ªª
( } BAcknowledgments
* EThanks to Tom Dowdy, Rob Johnson and Ingrid Kelly for reviewing this * NTechnote. Special thanks to Michael Fairman for proving that graphics is more * than what you can draw. ‡ª
